---
title: 'Run Cypress in GitLab CI: A Step-by-Step Guide'
description: 'Set up GitLab CI/CD to run Cypress tests with Docker images, caching, parallelization, and Cypress Cloud.'
sidebar_label: GitLab CI
---

<ProductHeading product="app" />

# Run Cypress in GitLab CI

:::info

##### <Icon name="question-circle" color="#4BBFD2" /> What you'll learn

- How to set up GitLab CI/CD to run Cypress tests
- How to cache dependencies and build artifacts
- How to parallelize Cypress tests with GitLab CI/CD
- How to use Cypress Cloud with GitLab CI/CD

:::

With its hosted
[CI/CD Service](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/),
[GitLab](https://gitlab.com) offers developers "a tool built into GitLab for
software development through the continuous methodologies".

Detailed documentation is available in the
[GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/).

## Basic Setup

The example below is basic CI setup and job using
[GitLab CI/CD](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/)
to run Cypress tests within the Electron browser. This GitLab CI configuration
is placed within `.gitlab-ci.yml`.

```yaml
stages:
  - test

test:
  image: node:latest
  stage: test
  script:
    # install dependencies
    - npm ci
    # start the server in the background
    - npm start &
    # run Cypress tests
    - npm run e2e
```

**How this configuration works:**

- On _push_ to this repository, this job will provision and start GitLab-hosted
  Linux instance for running the outlined `stages` declared in `script` within
  the `test` job section of the configuration.
- The code is checked out from the GitLab repository.
- Finally, our scripts will:
  - Install npm dependencies
  - Start the project web server (`npm start`)
  - Run the Cypress tests within the GitLab repository using Electron.

## Testing with Cypress Docker Images

The Cypress team maintains the official
[Docker Images](https://github.com/cypress-io/cypress-docker-images) for running
Cypress tests locally and in CI, which are built with Google Chrome, Mozilla Firefox and Microsoft Edge.
For example, this allows us to run the tests in Firefox by passing the
`--browser firefox` attribute to `cypress run`.

```yaml
stages:
  - test

test:
  image: cypress/browsers:22.15.0
  stage: test
  script:
    # install dependencies
    - npm ci
    # start the server in the background
    - npm start &
    # run Cypress tests
    - npx cypress run --browser firefox
```

## Caching Dependencies and Build Artifacts

Caching of dependencies and build artifacts can be accomplished with the `cache`
configuration. The
[caching documentation](https://docs.gitlab.com/ee/ci/caching/) contains all
options for caching dependencies and build artifacts across many different
workflows. Artifacts from a job can be defined by providing paths and an
optional expiry time.

```yaml
stages:
  - test

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/

test:
  image: cypress/browsers:22.15.0
  stage: test
  script:
    # install dependencies
    - npm ci
    # start the server in the background
    - npm start &
    # run Cypress tests
    - npx cypress run --browser firefox
  artifacts:
    when: always
    paths:
      - cypress/videos/**/*.mp4
      - cypress/screenshots/**/*.png
    expire_in: 1 day
```

## Parallelization

[Cypress Cloud](/cloud/get-started/introduction) offers the ability to
[parallelize and group test runs](/cloud/features/smart-orchestration/parallelization)
along with additional insights and [analytics](/cloud/features/analytics/overview) for
Cypress tests.

The addition of the
[`parallel` attribute](https://docs.gitlab.com/ee/ci/yaml/#parallel) to the
configuration of a job will allow us to run multiples instances of Cypress at
same time as we will see later in this section.

Before diving into an example of a parallelization setup, it is important to
understand the two different types of jobs that we will declare:

- **Install Job**: A job that installs and caches dependencies that will be used
  by subsequent jobs later in the GitLab CI workflow.
- **Worker Job**: A job that handles execution of Cypress tests and depends on
  the _install job_.

### Install Job

The separation of installation from test running is necessary when running
parallel jobs. It allows for reuse of various build steps aided by caching.

First, we will define the `build` stage along with `cache` and variables related
to the cache.

Then we define the `install` step that will be used by the worker jobs and
assign it to the `build` stage.

```yaml
stages:
  - build

## Set environment variables for folders in "cache" job settings
## for npm modules and Cypress binary
variables:
  npm_config_cache: '$CI_PROJECT_DIR/.npm'
  CYPRESS_CACHE_FOLDER: '$CI_PROJECT_DIR/cache/Cypress'

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - cache/Cypress
    - node_modules
    - build

## Install npm dependencies and Cypress
install:
  image: cypress/browsers:22.15.0
  stage: build
  script:
    - npm ci
```

### Worker Jobs

Next, we add a `test` stage and define the worker job named `ui-chrome-tests`
that will run Cypress tests with Chrome in parallel during the `test` stage.

The addition of the
[`parallel` attribute](https://docs.gitlab.com/ee/ci/yaml/#parallel) to the
configuration of a job will allow us to run multiples instances of Cypress at
same time.

:::info

The following configuration using the `--parallel` and `--record` flags to
[cypress run](/app/references/command-line#cypress-run) requires setting up
recording test results to [Cypress Cloud](/cloud/get-started/introduction).

:::

```yaml
stages:
  - build
  - test

## Set environment variables for folders in "cache" job settings
## for npm modules and Cypress binary
variables:
  npm_config_cache: '$CI_PROJECT_DIR/.npm'
  CYPRESS_CACHE_FOLDER: '$CI_PROJECT_DIR/cache/Cypress'

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .cache/*
    - cache/Cypress
    - node_modules
    - build

## Install npm dependencies and Cypress
install:
  image: cypress/browsers:22.15.0
  stage: build
  script:
    - npm ci

ui-chrome-tests:
  image: cypress/browsers:22.15.0
  stage: test
  parallel: 5
  script:
    # install dependencies
    - npm ci
    # start the server in the background
    - npm start &
    # run Cypress tests in parallel
    - npx cypress run --record --parallel --browser chrome --group UI-Chrome
```

## Using Cypress Cloud with GitLab CI/CD

In the GitLab CI configuration we have defined in the previous section, we are
leveraging three useful features of
[Cypress Cloud](/cloud/get-started/introduction):

<CiProviderCloudSteps />
